<!--
  ~ Copyright 2004-2014 Brian McCallister
  ~ Copyright 2010-2014 Ning, Inc.
  ~ Copyright 2014-2020 Groupon, Inc
  ~ Copyright 2020-2020 Equinix, Inc
  ~ Copyright 2014-2020 The Billing Project, LLC
  ~
  ~ The Billing Project licenses this file to you under the Apache License, version 2.0
  ~ (the "License"); you may not use this file except in compliance with the
  ~ License.  You may obtain a copy of the License at:
  ~
  ~    http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  ~ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
  ~ License for the specific language governing permissions and limitations
  ~ under the License.
  -->
<html>
<body>
    <h1>SQL Objects</h1>
    <p>
        The sql objects API allows for declarative definition of interfaces which will handle
        the generation of sql statements and queries on your behalf when needed. Take the following interface:
    </p>
    <code>
        public interface TheBasics
        {
            {@literal @}SqlUpdate("insert into something (id, name) values (:id, :name)")
            int insert({@literal @}BindBean Something something);

            {@literal @}SqlQuery("select id, name from something where id = :id")
            Something findById({@literal @}Bind("id") long id);
        }
    </code>
    <p>
        You obtain an instance of <code>TheBasics</code> via one of three means, the first opens a new
        handle against a DBI instance, the second attaches the object to an already open handle, and the third
        will obtain and release connections on demand against a DBI instance.
    </p>
    <code>
        DBI dbi = new DBI(dataSource);
        Handle handle = dbi.open();

        TheBasics via_open = dbi.open(TheBasics.class);
        TheBasics attached = handle.attach(TheBasics.class);
        TheBasics on_demand = dbi.onDemand(TheBasics.class);
    </code>

    <h1>Closing Objects</h1>
    <p>
        It is important to ensure you close the underlying handle on a sql object if it was opened via the DBI#open in
        particular.
    </p>
    <p>
        If the sql object defines a close() method, or includes it via another interface (such as the
        included CloseMe, or java.lang.AutoCloseable) calling that method will close the handle.
    </p>
    <p>
        On-demand sql objects should not be explicitly closed.
    </p>

    <h1>Mixin Interfaces</h1>
    <p>
        A number of mixin interfaces are included in the org.skife.jdbi.v2.sqlobject package. These provide additional
        functionality on your sql object, such as transactions or access to the underlying Handle instance. To make
        use of them just have your sql object interface extend the mixin interface.
    </p>
</body>
</html>
